home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
PD Collection CD 1
/
PD Collection CD 1.iso
/
textual
/
cite
/
support
/
Docs
/
Manual
< prev
next >
Wrap
Text File
|
1996-03-30
|
47KB
|
952 lines
Citation Database Manager (v1.5) Manual
========================================
CONTENTS
--------
1. Input
1.1 - Keyboard input
1.2 - File import
1.3 - #ID numbers
2. Output
2.1 Export Icon
2.2 Field Export
2.3 Generating Citations
2.3a Defining the style
2.3b Selecting references
2.3c Generating the output
3. Searching
3.1 First Author
3.2 Record #ID No.
3.3 General Search
4. Archiving
5. Configuration & Preferences
5.1 memory_transfer
5.2 Journals
5.3 Preferences
5.3a Archive opt(ion)s
5.3b Export "and" separator
5.3c Citation "and" separator
5.3d Export type
5.3e Brackets
5.3f Medlars Abstract
6. Misc
7. Errors
This package should included the following:
* !Citation - Main Application.
* Refsdata - example citation library, drag to the iconbar icon.
* Txtdata - an example bulk import text (see section 1.2 Bulk import).
* OldArch - a pre-v1.5 example archive file (see section 4. Archiving).
* NewArch - a v1.5 example archive file.
* Medlars - an example Medlars file.
* Docs directory - containing this Manual and some !Draw files showing
annotated screen shots.
What follows is a brief run down of the main features of !Citation -
don't be afraid to experiment using the supplied example data.
1. Input
========
"Where do I start?".... Load !Citation (double click in the icon in the
filer window) and drag a library (for example "Refsdata" supplied with
this package) to the !Citation icon on the iconbar (the big "C") and you
will see the main viewer window display the first record in the citation
library. Note that !Citation data libraries are actually application
directories which can be copied, moved and *DELETED* (though not whilst
it is being used by !Citation - please) as usual through the RISCOS filer
menus... so keeping backups is easy.
Shift-double clicking on a library (app directory) opens it to show the
data files, one not surprisingly called "data" and others called "0", "1"
etc. which are indexes. Do not alter these files or your data will be
corrupted - but of course you will always have that back-up...?? You will
also see the !Run and !Sprite files which are needed to define the
resource as an application directory.
"What about renaming the library?"..... Renaming these data resources has
always been a bit problematical (look at CC's Impression) because the
sprites in the sprite files need to be re-named as well as the directory
otherwise the icon will not be displayed. Unless you are familiar with
the workings of sprites and are happy with the former method, perhaps the
easiest way to rename a library is to create a new library with the
required name, open it, delete the empty data files and copy the full
data files into the new directory. Note that it is the library directory
that has a "name" not the data files.
"How do I create a *NEW* library?".... Simply open up the icon bar menu,
select "New Library", enter a name and drag to a filer window. Data files
will be automatically created in this directory by !Citation and an empty
viewer window displayed ready for data entry. The "!" prefix is
automatically added to the name if you forget.
If no library is loaded then the main viewer window opens with "No file
open - Waiting" and advice in the Title field to "Drag a citation library
to the iconbar...". Dragging a library to the iconbar immediately open
the file and displays the first record. If you have several libraries,
when the next is dragged to the iconbar and the current library is closed
and the new one opened.
"Close library" in the iconbar menu closes the current library and
returns !Citation to its waiting mode. This option is occasionally useful
since the pathname of the last active library is retained in a
configuration file so that !Citation always opens where you left off. If
this library moves or is deleted between running !Citation, !Citation
will report an error and open with "No file open". If you make a back-up
of the configuration file (see 5. Configuration) use the "close file"
option in the icon bar menu first. This zeros the active library to
"default" and prevents this error - but don't worry it is not a fatal if
it does occur!
1.1 - Keyboard input
--------------
We will deal with manual input first and describe the actions of the
icons on the main viewer card (see also accompanying !Draw file -
"viewer")....
Icons at the top of the card are grouped from left to right:
*Window header bar - shows the name of the active file, editing/adding
modes and the number of records in the library.
*Status window - shows the record #ID number.
*Goto first record arrow
*Goto previous record arrow - note "adjust" click on previous/next
arrows jumps 10 records and "select" just one record.
*Goto next record arrow
*Goto last record arrow
*Add a record - in this mode all arrow keys are disabled (in fact all
record movements) while a new record is manually added.
*Edit a record - once in this mode one can "browse edit" with arrow keys
to allow easy alteration of consecutive records. This also works with
secondary arrow icons in "Search" and "Generate subset" windows (see
later). In browse editing mode altered records will be automatically
updated if user moves to a new record (ie. clicks on an arrow in the main
viewer window) but you must use "Save" on the last altered record if
leaving this mode, to update the file. This also applies to the secondary
arrows other windows (see below).
*Delete - flags the current record as deleted. Note records are not
removed until the file is "Compacted" from the icon bar menu ("Compact
library") since this can be a time consuming process and best executed in
bulk. No attempt is made to stop the user editing deleted records. These
will be lost on the next compact but can be reinstated BEFORE compacting
using the "Main menu>Misc>Undelete" option.
*Cancel - abort current operation and reinstate altered fields.
*Save - update any changes to disc (note comment in Edit above). Only
one record is ever held in memory so that if the system crashes data loss
is minimal.
*Export icon allows dragging of author names directly into your paper in
the appropriate format eg. "[Radulescu et al, 1986]" or "[Smith & Jones,
1801]". (see 2. Output, for difference between select/adjust drags)
If no file is open then all icons are disabled. If a new, empty data file
is selected then only the "add" icon functions.
Now to the nitty-gritty of typing. !Citation needs to have authors
entered in a specified format to provide a known starting point from
which the various output formats can be derived. Authors should be
entered as: SURNAME, SPACE then INITIALS with no spaces between initials
eg. Brown FG, Williams ED. !Citation assumes that all the characters
*AFTER* the last space separator are the initials so that double-barreled
or complex surnames with several part can be used eg.
Wynford-Thomas D ("D" is the initial)
Yo Ti Wa XF ("XF" are taken as the initials)
de Cuevas BA ("BA" are taken as the initials)
Minster (Jean-Francois) J-F ("J-F" are taken as the initials)
The FRAM Group ("Group" is interpreted as initials)
The last example represents a special case since it is likely that the
user would wish to treat this author string as as a single entity. To
indicate this, all the elements of the string *MUST* be joined by a
hyphen or similar unique separator thus:
The-FRAM-Group or The#FRAM#Group
!Citation will then handle this string as a "surname" only with no
initials. The separator may then later be removed by "Search & Replace"
in the final copy.
Note also, that provided punctuation of Authors fields is not required
(in "Author Options", Citation styles window), full first names may also
be used eg. Bond James.
Up to ten authors can be specified and the "et al" icon can be selected
at any time to add "..., et al" to the author output. Note that this icon
is automatically selected if more than 10 authors are detected on bulk
input, to flag to the user that more authors exist than can be
accommodated by !Citation. Each maximum author length is 23 characters
for surname and initials (...technical limitations I'm afraid but should
be enough for most purposes).
Title and Notes fields have a 254 character limit.
The source fields comprise:
Journal/Book title - 55 chars
Editors - 30 chars
Publisher - 25 chars
ISBN/Place - 25 chars
volume - 10 chars
pages - 15 chars
date - 15 chars
These are essentially free format so that dates can be 1967 or 1973a or
13th Sept 1856. Similarly, pages and volume can contain letters to allow
for example supplement page numbers "s11-s45". This flexibility
essentially means that there can be no validation check on these fields
for, say, numerical input only.
A "select" click on the menu icon which sits by the Source header brings
up a menu of your preferred journals (see 5. Configuration, for
information on how to edit this list). If you are in adding/editing mode
then clicking on an item in this menu inserts it into the Journal/Book
title field, otherwise the options are greyed out (unselectable).
The Keyword field can be upto 55 characters in length and can be used in
any manner you wish, with or without separators between words.
"How do I start adding references?".... Clicking on the "Add" icon will
clear the card ready for input. The cursor will be initially in the First
Author field but can be moved to another field by clicking into it or
using "Tab" or "Return" to step through fields. "Tab" will step though
groups of fields so that if there is only one author to enter, "Tab" will
jump on to Title whereas "Return" steps through individual fields
sequentially.
The left/right cursor keys move within a field and with shift or ctrl
effecting larger steps. Text in the longer fields will word wrap and
scroll if necessary. Shift-Tab moves to the previous field. Ctrl-U clears
a field and other standard RISCOS protocols apply.
"Page up/down" or shift up/down arrows will allow browsing through
records, mimicking clicking on the forward/back icons with "select".
Note the "Paper type" and "Copy?" icons which give a quick visual
reminder to the paper type or possession of a hard copy.
A format card is available, which, in the adding mode, allowing authors,
title, notes, papertype, copy, etal, keywords etc. *AS WELL AS* the
subset assignments (see defining subsets in section 2.3b), to be
duplicated over several additions. This is accessed from the
"Main Menu>Format card>Edit format". Remember to toggle this option ON
with "Format card>Use format". A tick by this item in the menu indicates
the format card is active. Toggle OFF after use.
1.2 - File import
-----------
The file import window is accessed from the "Main Menu->File import".
This window is used for three types of importing: 1) Citation archive
files, dealt with later, 2) So called "Five-line text" files and 3)
Medlar formatted files.
The "five-line" text files are a useful option, as described in the
introduction. Personally I keep a list of my current references in a text
file on my Psion/Pocket book as a plain text file, adding to this list as
I come across new references. This saves long typing sessions and keeps
me organized...!
The five-line file has the following format:
start of file...
au,au,au[CR]
title[CR]
journal_title,vol,pages,yr[CR]
notes[CR]
[CR]
...end of file
There is a new line (CR or LF not both) after each line and after the
last line of the last reference. The authors and source lines are
formatted as comma separated variables and if no "notes" are included a
blank line should *STILL* be present, so that there are *TWO* blank lines
after the "Journal_title" line before the next reference (see the
accompanying "Txtdata" file for an example).
Thus there are 4 lines carrying the information and a 5th blank
terminator line (this is used as a rough check that the file is in the
correct format before import). The 5-line format however doesn't cater
for the extra book fields in the database which will have to be entered
manually.
"How do I import my 5-line text file?".... Open the File import window,
ensure the 5-line/Medlar is appropriately set and drag your text file
into the window. (The import window only accepts CSV files, which it
assumes are archives and text-type files which are assumed to be either
5-line or Medlars input depending on the button setting.) You will be
informed that the file format will be checked first and given the option
to continue or cancel. I have found, from experience, that despite this
simple file structure it is easy to put an extra CR/LF in by mistake or
forget to leave a blank line between references or a blank line for the
"notes" if none are present. This would cause a synchronization error on
import with fields being entered out-of-step.
To prevent this Citation checks that each entry comprises 4 lines
followed by a blank 5th line and if a non-blank 5th line is detected an
error is flagged with an indication of roughly (+/- 1) around which entry
the error lies. The file length is also checked to see if it accords with
the number of entries. Lines of over 254 characters (this applies
primarily to "title" and "notes" fields) are automatically truncated and
">>" added to the end to indicate this. No other warning is issued.
If the format is OK then the user is asked whether to continue with the
import. If a format error is flagged, check the file at the indicated
place, correct the error and begin the process again. The error checking
routine is fairly simple and aborts on the first error encountered. It
might require several runs to debug a file that contains multiple errors
but this is better than having all the fields out-of-synch. Importing
occurs at about 40 references/min on an old ARM3 A410 (time for a cuppa!)
but should be faster on newer models.
"What about Medlars files?".... Medlar files are a standard format
produced by some computerized journal databases specifically for
importing into bibliography managers. I use this facility on MedLine
which is the main database in the medical field but since this format is
widely used by bibliography managers on other platforms (Endnote &
Papyrus) I guess it is fairly universal. An example file is included with
this package.
Importing is through the same window but select the Medlars button BEFORE
dragging the file. Confirmation for import is requested and then the
whole file is directly imported on the assumption that, being machine
created, there is no need to pre-check. However if you edit your file
first to select out the desired references be sure to leave the
individual references intact. These have a 6 character leader to each
line which either contains a field assignment eg "AU - " or 6 spaces for
continuing assignments. Each reference is terminated by a blank line. All
these are required for !Citation to work out what goes where!! So the
message is... edit with care...
You will also see from the example file that I have assumed that these
will be DOS files with both a CR and LF at the end of each line.
!Citation will handle this automatically - there is NO NEED to strip out
CRs - in fact if you do, this will mess up the routine. If you have a
system that doesn't use DOS let me know and I can make a simple change to
the routine to account for single LFs of CRs.
"Can I replicate some fields over a series of file import cards?"...
Yep.. With both types of file import, the Format card (Main Menu>Format
card>Edit Format) can be used to set "papertype", "copy?" & keywords.
The keyword option in particular, provides an easy means of grouping
papers since a particular keyword can be searched for and autoadded to a
Subset for output (see 3.3 General search). Don't forget to toggle
"Main Menu>Format card>Use format" ON (ie. ticked) and untick after
use.
"Oh <substitute expletive>! I imported the wrong file... What can I do?"
Have a cuppa and calm down... If you import the wrong batch of references
or an error occurs and the file is half imported you can use the "Delete
import" option from the "Main Menu>Misc>Delete import" to remove all of
the last imported references and compact the file. If you have other
deleted records in the file, this process also removes them - beware...
Note this only works within a session. If you quit and restart !Citation
the import pointers are lost.
The user can also directly import text files to the Author, Title and
Notes fields of the displayed record by drag'n'drop on the appropriate
field. Note that this can ONLY be done in editing/adding mode. Authors
should be comma separated and in the usual format. If a mistake is made
"Cancel" will usually reinstate the previous text. Text also can be
exported from these fields (see 2. Output) which means that !Edit can be
easily used as a tool for editing long fields, re-importing after
alterations.
1.3 - #ID Numbers
-----------
Each reference in !Citation is allocated a unique identity number (#ID)
which is indicated in the status window as "No. #xxxx". To ensure that
the #ID numbers are indeed unique they are assigned sequentially as
records are added. Thus for a group of records in which there have been
no deletions, these #ID numbers run sequentially but as records are
deleted, gaps in the sequence may appear but this is of little
consequence to the user.
Two options are provided to manage record #ID numbers. "Main Menu>
Misc>Reset #ID No." leads to a small window which shows the #ID number
which will be assigned to the next entry and allows the user to change
this "seed" value. This must be done with EXTREME caution since you may
well end up generating duplicate #ID numbers and there is little error
checking in this routine - alterations require confirmation through a
warning box. Altering this "seed" value may be of use if you need to add
a group of records originating from another application (de-archive or
file import) which require specific #ID numbers, though I am sure other
occasions may present themselves.
The other option, "Main Menu>Misc>Alter #ID No.", allows the user to
alter the #ID number of the record currently shown in main viewer window.
Again caution is advised but this routine checks for invalid or duplicate
number or warns the user that the #ID lies outside the current range and
may be duplicated later
2. Output
=========
Output from !Citation can be performed in 3 ways.
2.1 - Export Icon
-----------
A "select" drag from the Export Icon (green arrow, top right of main
window) gives "[authors & yr]" only from the current reference shown in
the card. This is useful if you have !Citation running as your are
writing and want to insert the currently displayed author into the
paper's text. !Citation automatically works out the appropriate author
format and puts this into the paper with the year surrounded by
parentheses. This should work with any type of wordprocessor/DTP package
and uses file or direct memory transfer. Alternatively an "adjust" drag
from export icon give full citation in the defined citation style (see
section 2.3a).
2.2 - Field Export
------------
As mentioned in section 1.2, the Author, Title and Notes fields can be
directly exported to file or to an application through direct memory
transfer by dragging from the small green arrow adjacent to their header
icons (see the !Draw file "viewer"). Note that text can be dragged
directly back into those fields *ONLY* when !Citation is in the editing/
adding mode.
2.3 - Generating citations for final output to a technical paper
----------------------------------------------------------
This comprises three parts a) defining the style of the output
references, b) selecting which references within the database are for
output and c) generating the output set.
2.3a - Defining the Style
------------------
The essence of !Citation is the ability to output references in any
desired format. Styles are set up in the the Citation style window (Main
Menu>Citation style, see also the !Draw file "style") and allow any
style of output using certain command words. These are (note lower case
and exact spelling):
Command Output
------- ------
idn Unique ID no.
auth Authors in given format
title Piece title
sot Source (Journal/Book) title
vol Volume field
pgs Page field
date Obvious really!
eds Editor field
pub Publisher field
isbn ISBN/Place field
keys Keywords field
note Notes fields
* Tab char [09]
/ New line [LF]
They are mostly self explanatory. Any or all of the command words can be
combined in any order with any punctuation or special characters (*/) as
indicated above eg.
auth (date)./title/{italic on}sot{italic}/vol;pgs
This would output the authors followed by a space, date in parentheses
followed by a full-stop, new-line, title, new-line, curly brackets
containing the words "italic on" followed directly by the source and
"{italic}" again. A new-line is inserted before volume number which is
followed by a semi-colon and page numbers.
Anything which !Citation encounters in the style format which is not a
command word or */ is simply included in the output at the appropriate
place eg. all punctuation (including spaces) and strings like {italic}.
Note that the expressions in {curly brackets} are text formatting
commands recognised by Impression which allow automatic conversion of the
enclosed text into the specified style (see CC's Impression/Style manual
- "Advanced Search and Replace" or set up some styles and export the text
story with "Styles Set". The exported text will show the correct format).
Thus in this case the "source" field will be italicized - a requirement
of some journals.
Three journal styles and 3 book styles, are stored in !Citation and these
are saved in a configuration file (see 5. Configuration). Select which
style you wish to use with the radio buttons by each style. To return to
the default settings use the "Iconbar Menu>Citation styles>Default"
(note this will replace your currently stored styles on exit). To restore
the last saved styles to the current style window use the "Iconbar
Menu>Citation styles>Restore".
The Author options in Citation style window allows surname and initials
to be reversed (from that shown in the viewer window), surname to be
capitalized, and initials to be punctuated with a full stop, space or
"#". The latter is sufficiently unusual to allow later search and replace
in !Edit to convert to more esoteric separators if desired. The "With
and" option allows automatic insertion of "and" or "&" (see Configuration
5.3b, 5.3c) before the penultimate author if required.
Book Styles
-----------
Book references often require a slightly different output format from the
standard journal format so !Citation automatically detects references
which are of "book" type from the "Type" setting (viz. Paper/Review/Book)
in the main viewer window and uses the selected "Book" format specified
in the !Citation styles window. eg.
Authors: Ears BG
Noddy TB
Title: The role of toys in child development.
J/B title: Symposium on Child Health and Development
Editors: Caroll L and Seagull L
Publisher: Churchill Livingstone
ISBN: 1234-4569-7894
Pages: 124-134
Year: 1985
The book format of:
auth (date)/title In: sot. Eds.: eds, Publisher: pub. ISBN isbn pp pgs
will then output:
Ears BG, Noddy TB (1985)
The role of toys in child development. In: Symposium on Child Health and
Development. Eds.: Caroll L and Seagull L, Publisher: Churchill
Livingstone. ISBN 1234-4569-7894. pp 124-134
2.3b - Selecting references for output
-------------------------------
!Citation uses the idea of "Subsets" to select which references are for
output, such that any record in the file can be included in a "Subset" of
references. This simply means that each record holds a flag (actually 5
flags) which indicates whether that record is a member of a particular
Subset.
There are up to 5 Subsets (hence 5 flags, numbered 0 to 4) and any record
can be a member of any one or more of these Subsets or none. The Subset
status for any record is shown in the "Define subset" window (Main
Menu>Citation subsets>Define subsets, see !Draw file "subsets"). This
window is an extension of the information seen in the main viewer and
changes as the user browses the file. A reference is included in a Subset
if the button by the Subset number (0 to 4) is ticked. The field next to
this button, which contains a number will turn yellow if the
corresponding set is selected - this is the "Ordering value" (we will
return to this below).
To select a Subset of references for output, one browses through the file
to find the desired references and each time clicks on a Subset button to
include that reference. With 5 Subsets, the user can have say, 5 papers
on the go at any one time each defining a discrete Subset, though of
course any one record may be a member of several Subsets. This method,
particularly in combination with the various search options (see below),
allows references to be easily added or removed from a Subset. The "Clear
subset" option (Main Menu>Citation subsets>Clear subset) will clear any
selected subset of ALL members - use wisely.
It is thus essentially very easy to build up a Subset but what about the
output order? In most cases journal require references to be arranged in
alphabetical order, which can be performed automatically by !Citation but
what about those that require references to be arranged in a particular
order - usually the order in which the references occur in the text? This
is where the "Ordering value" comes into play. This is simply a value
which indicates to !Citation the order which the user would like the
references to be arranged on output - note it is NOT the number which is
printed by the reference on the final output but a value which simply
determines the order in which references are organised in the final
output. Thus the Ordering values do not need to be consecutive eg. if
ref1=(10), ref2=(20), ref3=(15) the output will be.... 1. ref1 2. ref3
3. ref2
In fact the bump icons in this window can increment in steps of 1 or 10
depending on whether the are "select" or "adjust" clicked and I would
recommend that the user uses large steps so that is is easy to go back an
insert or reorder the references as the paper evolves.
The process of setting the Ordering value is an extension of selecting
the record as a Subset member. Once the Subset button is ticked the
ordering field becomes available (ie. goes yellow). You should see the
cursor in this field, if not click in it to put the cursor there, then
either use the bump icons to increment/decrement the value (0 to 999) or
enter a value manually. One only needs to click on the "Save" icon
(bottom right of the card) if manually inputting a number into Ordering
value. Clicking on the bump icons updates the record automatically. Once
the Ordering value is given move on to the next record...and so on. Note
that if the user only requires an alphabetical output the Ordering value
can be ignored.
The Subset selection buttons or Ordering values for a record can be
changed at anytime and are stored with the record until the Subset is
cleared.
2.3c - Generating the output subset
----------------------------
We now have a citation output style and a Subset (or more) defined and we
can output the Subset to the paper. Opening the Main Menu>Citation
subsets>Generate set window shows the 5 possible subsets, the Order
options, Go, Clear and Arrow icons (see !Draw file "subsets"). First
select the Subset for output using the "Subset" radio buttons and then
the desired output order. This is "plain Alphabetical", "Numbered
alphabetical" and "Ordered" ie. according to the Ordering values. Click
on the "Go" icon and !Citation searches the database to collect together
all records which are members of that subset. The arrow keys can now be
used to browse through the set to check the order and membership. The
status window in this card indicates the browse position in the Subset.
Note that once !Citation has calculated this group, altering the
membership of the Subset with the "Define set" window has no effect until
the process is "Clear"ed and started again. The final step is to click on
the Generate subset icon (blue icon by the status window) and a save box
is shown for the user to drag the set to file or directly into the paper.
3. Searching
=========
Three forms of searching are supported a) First Author, b) Record #ID
number and c) General Search (see !Draw file "search").
3.1 - First Author
------------
!Citation maintains an index of First author names as they are entered
which allows very rapid searching. Opening the search window (Main
Menu>Search>1st author) shows a yellow string entry field. Click in
this field and begin entering the surname. Each letter is grabbed by
!Citation as it is entered and the file updated to the nearest match. If
the sequence of letters thusfar entered (which need not necessarily be
the whole name) is not found then !Citation bleeps and flags "Not found"
in the main card status window. The arrow keys on the search card allow
alphabetical browsing of the file either around your found surname or if
the field is empty, through the whole file. The user can, in this way,
search for an author and once found browse round related papers.
If there appears to be a problem with the alphabetical ordering it may be
because the author index has become outdated. This shouldn't often happen
but may occur after multiple file imports and deletes. In this case re-
index the file using the "Re-index" option on the iconbar menu - this
doesn't take long. An out-of-date index does not affect the "Generation
subset" option since this creates its own new index each time.
3.2 - Record #ID No.
--------------
This simply accesses any record by its unique #ID number so that the user
can go directly to any reference. The card number is entered into the
entry field and pressing <Rtn> activates the find.
3.3 - General Search
--------------
For more extensive searches, including all Authors, Keywords, Sources and
Subject (ie. Title, Keyword and Note fields combined) use the general
search option (Main Menu>Search>General Search).
The "Search range" on the general search card is self evident. "Authors"
searches ALL authors (unlike the first author search). "Subject" searches
Title, Keywords and Notes for the search string. "Keywords" searches
keywords only - useful for defining a Set. The search string is case
independent and the search performs a simple - "does the field specified
in the search range *contain* the search string".
This window bears some similarities in function to the "Generate subset"
window in that a search string is entered and "Go" clicked (pressing
<Rtn> after typing the search string mimics clicking on "Go"). The number
of finds is flagged in the status window and the arrow icons allow
browsing (and editing) through the found records with the status window
indicating the position of the record in the found group. Before entering
another search string the current search needs to be cleared with the
"Clear" icon.
Searching with an empty search string selects all records. This could be
useful if you wish to output all references in a file, perhaps to import
to another application (note that there is also an archive option which
produces a CSV output of the entire file, see section 4.). Defining the
citation style with commas or tabs separating fields allows a CSV or TSV
formatted output (TSV though obviates any problems with the commas
separating authors).
The "Autoadd" option adds all finds to a specified Subset but does not
provide an Ordering value. This is useful if the user has a group of
records characterized by a specific term in the subject or keywords
fields. These can be searched out and added to a Subset ready for output.
An ordering value can be added by selecting the Subset using the
"Generate subset" option with alphabetical ordering and stepping though
the Subset updating the Ordering value as necessary.
4. Archiving
============
Selecting "Archive" from the iconbar menu archives the main fields (ie.
Author, Title, Source, Year) of the *ENTIRE* current library into a CSV
format file. It is also possible to include the other ancillary fields
usually held in a Citation record, viz. identity number, notes and button
fields into the file by altering the "Archive opts" in the "Icon Bar Menu
-> Preferences..." window (see section 5.2 for Archiving options). The
button fields, "etal", "papertype" and "Copy?", are converted to text
values in the process (ie. to etal_on/off, copy_on/off and research/
review/book - see example Archive file) to make the file more readable.
In contravention to the CSV standard, the archive file carries a one line
header which provides general information on the creation date etc. but
more importantly for Citation, specifies the presence of ancillary
fields. This header shouldn't cause much of a problem in general use and
can be deleted if the archive is not intended for use with Citation (see
Technical info below).
The archive options are by default set to include all fields except the
identity numbers which is a suitable configuration for the following
operations.
The first major use of archiving is for the combining libraries. Simply
load and archive each of the libraries you wish transfer, then open the
receiving library and drag the CSV archive files to the file import
window (Main Menu->File import). !Citation will detect that this is a CSV
archive file (rather than a 5-line text or Medlar file) and a warning
will be flagged asking for confirmation of dearchiving. If accepted the
archived data will be added to the end of the receiving library data with
new ID numbers allocated.
The second major use is for "future-proofing" !Citation. Should a later
version of !Citation require a change in the structure of the data file
then data can simply be archived out of the old version and imported into
the new version. If it is necessary to preserve the unique identity
numbers of your old library, set the archive option accordingly (see
section 5.2 for Archiving options).
Other possible uses include, of course, importing of the whole file into
any application that accepts CSV format files and importing CSV data into
!Citation. In the former case, remember to delete the one line header or
substitute it for a CSV description header before importing into your
alternative application.
Importing a CSV file into !Citation, could be problematic. !Citation
expects the file to be machine created and so minimal error checking is
employed on de-archiving. As you can see from the example Archive file
(load it into !Edit), it is quite complex and easy to make errors if
manually created. The only advantage of this type of import over the 5-
line text type (see section 1.2 File Import) is again the ability to
include "button" fields and keywords in the data. If you do attempt CSV
import, make a backup of the receiving library first!
Technical info
--------------
If you intend just use the Citation Archive files within Citation ignore
the following section.
If you wish to import CSV files from another application then you will
need to know how to provide a header with the information Citation needs
to make sense of the file. A header created by Citation will look
something like this...
"Citation Archive file. Created: 31/08/95.19:22:55 Ancillary Fields:
keywords, notes, buttons"
... and it is all quite simple really.
Citation first checks for the presence of the string "Citation Archive"
in the header (note this is case sensitive). This is to trap incompatible
files, so that in creating your own a header, this string must be present
somewhere in the header line. The creation date and " Ancillary fields:"
string are not validated and can be ignored.
Secondly, Citation assumes that the CSV file contains at least the
standard fields of 10 authors, title, source, volume, page and year. If
ancillary fields are to be included then the following strings must be
included in the header for each field present:
"#IDN" - for the identity number
"keywords" - for 5 keyword fields
"notes" - for the notes field
"buttons" - for the 3 button fields "etal", "papertype" and "copy"
The order of the fields and format of the button values are obviously
important and can easily be gleaned from examining the example archive
file.
Thus to import a CSV file containing references with a unique ID no. and
keywords, a suitable header would be:
"Citation Archive #IDN keywords"
I hope this is sufficient explanation but since this is a subject which
is only likely to be of interest to a minority of users it doesn't
warrant a voluminous exposition. You are welcome to Email me for more
info.
5. Configuration & Preferences
==============================
There are 3 configuration files in the !Citation application directory
(to open Shiftdouble click on !Citation), namely "config", "settings"
and "options".
"config" is used by the SBase exec program which runs !Citation (which is
in intermediate code) - this file should not be changed.
"settings" is similarly sacrosanct! This file is read by !Citation on
start up and is updated on closing the application. It holds your
preferred citation styles (amongst other things) and if this file is
corrupted or lost !Citation will report an error on startup and uses
defaults. A new 'settings' file will be created on exit but your previous
styles will be lost. You may like to keep a back up.
The last active file is also stored here, so if this moves or is deleted
between running !Citation, !Citation will report an error on next start-
up and open with "No file open". If you make a back up of this file use,
the "Close library" option in the icon bar menu first, which zeros the
active file to default and prevents this error - don't worry it is not a
fatal error if it does occur!
The "Citation styles>Default" option on the icon bar menu deletes all
your preferred styles and returns to the defaults. Your preferred styles
will be lost - beware (but may be restored with "Citation styles>
Restore" before exiting).
The "options" file however, is fair game for alteration by loading into
!Edit. It needs a bit of explanation first, but essentially looks like
this:
File Start.....
***** Options - change carefully. See manual *****
memory_transfer ON
***** Add Journals Below *****
Nature
Science
J. Endocrinol
Mol Cell Biol
*END*
...File End
The "Options" section contains (at the moment just one) configuration
features which will rarely need altering once set up. Please alter only
the appropriate parts (eg. ON/OFF). Adding lines (journal names excepted)
or changing the order may have unexpected effects. Note that alterations
to these options only take effect when !Citation is run.
5.1 - memory_transfer ON/OFF (default ON).
------------------------------------
A problem has been reported with direct drag'n'drop memory transfer to
other applications (eg. dragging from the "Export" icon to a WP) causing
!Citation to crash - in particular to earlier versions of !Techwriter.
The cause of this is, in the case of !Techwriter, rather technical but
one (possibly slightly inelegant) solution is to avoid memory transfers
altogether and use the <WimpScrap> directory instead - hence this option.
With memory_transfer OFF, Drag'n'Drop works just as with before but your
disc will spin up. The disadvantages are that it is a little slower and
you really do need a hard drive.
No problems with memory transfer have been found with !Edit, !Zap,
!Artworks, !Style, !Publisher, !Draw(+) and for the most part you can
leave the option ON. (My thanks to Peter Killworth and the folks at Icon
Technology for their help with this one.) Note the latest version of
Techwriter should now work with memory transfer.
5.2 - Journals
--------
A list of your favourite journals can be included in this file below the
indicated "*****" separator. These should be entered as one journal per
line with no empty lines between journal names and do not remove the
"*END*" marker. Any number of entries may be added but the sum total
length for the whole list cannot exceed 255 characters. Entries over this
limit will be ignored.
5.3 - Preferences
-----------
A preference window can be called up from the icon bar menu which allows
the setting of various parameters whilst Citation is running. All but the
Archive opts are saved in the "settings" file on exiting the application.
There is no "OK" icon in this window since all options are immediately
effective and it is closed by clicking elsewhere or on the close cross.
5.3a - Archive opt(ion)s
This allows selection of the ancillary fields to be included in an
archive file (see section 4. on Archiving). These settings are *NOT*
saved on exiting and will always default to ID no. OFF, keywords ON,
notes ON and buttons ON on starting the application. This is to try and
obviate the possibility of accidentally saving an archive with ID nos set
and creating duplicates.
Note that the warning box which asks for confirmation of de-archiving
also shows which ancillary fields (if any) have been flagged in the
header line.
5.3b - Export "and" separator
A select drag from the "Export" icon (section 2.1) can be used to put the
author name and year in a document. The default setting for a two author
entry is [Smith & Jones, 1995] ie. using the ampersand symbol as a
separator. This option setting may be changed, if desired, to give the
letter form ie. [Smith and Jones, 1995].
5.3c - Citation "and" separator
An option is available in the Author formatting in the Citation style
window to place an "and" separator before the penultimate author name
viz. Henery GH, Williams DW, Jones FG and James DS. The default setting
is the letter form of "and" but may be changed to the ampersand symbol,
if required, by altering this option setting accordingly.
5.3d - Export type
A select drag from the "Export" icon (section 2.1) can be used to put the
author name and year in a document. Selecting "#IDN" prefixes this output
with the reference ID number eg. [#0234-Smith & Jones, 1995]. This is
mainly intended for automatic citation generation (not implemented in
this version) but might also prove useful for quickly back-referencing
from the manuscript.
5.3e - Brackets
A select drag from the "Export" icon (section 2.1) can be used to put the
author name and year in a document. The default setting is to enclose
this string in square brackets but round or curly brackets can be
selected with this option.
5.3f - Medlars Abstract
Medlar file abstracts are generally quite long and don't fit into the
"Notes" field without considerable truncation thereby making them fairly
useless. Unticking this option causes !Citation to ignore the abstract
section of a Medlar reference and leave the space for your own, more
succinct notes!
6. Misc
=======
* Note that "Compact"ing the library (icon bar menu) closes any active
Search or Subset queries first since these may contain references which
are flagged deleted and therefore removed from the file. Use this option
cautiously.
* The "Delete all records" option in the icon bar menu does just that for
the entire library...do keep regular backups of your data.
* There are some hot keys which work ONLY when the main card has the
input focus:
ctrl-D, open Define Subset window
ctrl-S, open General Search window
ctrl-A, open First Author search window
ctrl-N, open Record by #ID no.
ctrl-G, open Generate Set window
* Clicking on the close cross - top left of the main viewer window, hides
this window as well as any other window related to !Citation. The file is
NOT closed and "select" clicking on the iconbar icon reopens the main
viewer window and any related windows (search, define subsets etc). This
is useful for maintaining an uncluttered desktop whilst working on your
WP and you can easily flick back and forth to insert citations.
* Most database files (including this one) use fixed length fields. A
record uses about 1kb so a fair sized library can be stored on a 1.6 Mb
floppy for backup (say, over a 1500). However, since most records contain
numerous redundant spaces a compression utility (!Spark, !Compression
etc) will achieve significant a space saving.
7. Errors
=========
I have tried to prevent most errors occurring by design but those obvious
ones which escape are covered by appropriate error handlers (usually
where data is imported or exported and the media may be faulty/not
present). Error reports are mostly informative but S-base exec does not
support many error messages so you might get something like "Error 107"
or similar. A click on "OK" will abort most errors and !Citation will
fail-safe.
A global error handler, however, is provided to capture unforeseen errors
and flags, "!Citation has encountered a fatal error and must exit
immediately. No data should be lost (see manual)." After exiting,
!Citation then writes an error code to the "settings" file (see section
5.). Immediately after experiencing such an error (preferably before
running !Citation again), make a copy of your "settings" file and send it
to me for diagnosis.
Happy writing....